/*******************************************************************************
 * @file Copyright 2009 The CREATE Lab at CMU
 * 
 *       This file is part of JubJub, an open source project.
 *       http://code.google.com/p/jubjub/
 * 
 *       Redistribution and use in source and binary forms, with or without
 *       modification, are permitted provided that the following conditions are
 *       met:
 * 
 *       Redistributions of source code must retain the above copyright notice,
 *       this list of conditions and the following disclaimer.
 * 
 *       Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 * 
 *       Neither the name of Carnegie Mellon nor the names of its contributors
 *       may be used to endorse or promote products derived from this software
 *       without specific prior written permission.
 * 
 *       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *       "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *       LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 *       PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 *       HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 *       SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 *       LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *       DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 *       THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 *       (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 *       OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *******************************************************************************/

package edu.cmu.ri.createlab.jj.blocks;

import edu.cmu.ri.createlab.jj.blocks.BlockDefs.*;
import edu.cmu.ri.createlab.jj.visitors.*;
import edu.cmu.ri.createlab.jj.projects.*;

/**
 * @file BlockInterface.java
 * @author Erik Pasternak
 * @brief Defines interaction with blocks in Jubjub
 *
 */

/**
 * Defines interactions common to all blocks.
 * 
 * Blocks need to have certain fields to allow them to be identified
 * and named properly. Thus, they all implement the BlockInterface.
 */
public interface BlockInterface
{
   /// sets the comment for this block
   public void setComment(String comment);
   /// gets the comment for this block
   public String getComment();
   /// returns the Class this Block belongs to.
   public JJClass getOwner();
   /// set the name of the class this block belongs to
   public void setOwner(JJClass owner);
   /// returns the name of this Block.
   public String getName();
   /// sets the name of the block
   public void setName(String name) throws Exception;
   /// returns the type of this Block, defined in BlockDefs BlockTypes.
   public BlockTypes getType();
   /// returns the ID number of this block. These are generated sequentially
   /// for each project or library.
   public int getID();
   ///Add a reference to this block. Blocks should keep track of where they
   ///are used so they can update their references when they change.
   public void addRef(RefBlock ref);
   ///remove a reference to this block
   public void remRef(RefBlock ref);
   ///Update all references to this block. Should be used when the block changes.
   public void updateRefs();
   ///Return whether this block is still valid or if it is deleted pending
   ///removal of all its refs.
   public boolean isValid();
   ///Sets this block to not Valid and updates all its refs
   public void deleteBlock();
   ///Sets this block to valid and updates all its refs
   public void undeleteBlock();
   ///Removes all references contained by this block. This should only be called
   ///prior to permanently removing all references to this block.
   public void destroyBlock();
   ///Return whether this block currently has an error
   public boolean hasError();
   ///Check the error state for this block
   public void checkError();
   
   /// All blocks need to accept Block Visitors, which perform operations like
   /// writing to Java or painting on the screen.
   public BVReturn accept(BlockVisitorInterface bv);
}
